Directory & File Selection "As a jewel of gold in a swines snout, so is a fair woman which is without discretion" Proverbs 11.22 Introduction The GOLDDIR unit includes a set of customizable dialogs which perform the following duties: Displays a file open/close dialog with files, directories, drives and file masks listed … la Windows. Displays a multi-column list of files (and optionally directories/drives) allowing the user to select a file. Displays a Directory Selector/Changer dialog to allow the user to navigate around drives and directories. Figure 6.1 The PromptFile dialog Using PromptFile to Choose a File The PromptFile function in GOLDDIR is defined as follows: PromptFile(FullFilename:PathStr): StrScreen; Displays a file selection dialog allowing the user to enter an explicit filename or to navigate around the drives and directories and select a file from the list. The only parameter is a string that specifies the default mask/filename that will be displayed in the Filename field when the dialog is first displayed. If the string includes a path, the dialog will fill the directory and drive list with the specified path as the current selection. The function returns the fully qualified filename of the selected file, or a null string if the user escaped/cancelled. The demo file DEMDIR1.PAS shows how easily a file dialog can be displayed. (See figure 6.1). Adding Custom Help By default, the PromptFile dialog does not include a help button. However, a help button will automatically appear (as if by magic) when you use the following procedure: AssignDirHelpHook(PFHook: PromptHelpHook); Assigns a help procedure to a PromptFile or PromptDir dialog. The passed procedure must be declared far and have no passed parameters. The hooked procedure will be called whenever the user selects the Help button. To subsequently remove the Help button, call the procedure RemoveDirhelpHook before displaying the dialog. Run DEMDIR2.PAS (or DEMDIR6.PAS) for a demonstration of the custom help facility. Ensuring a File Exists Users can manually enter a filename in the filename field of the dialog, rather than selecting from the list of files. You can ensure the user only enters the name of an existing file by setting the value of DirsVars.ExistOnly to true. If the user tries to enter a file which does not exist, an error message is displayed and the user is returned to the dialog. Customizing the PromptFile Dialog By default, the PromptFile dialog is constructed as a file open dialog. However, the window title, button text and button hotkeys can all be customized to change the flavor of the dialog. International developers can easily change all the dialog text and messages to a different language. The DirVars record variable includes the following variables which influence the displayed text: Changing the Window Title The following variable controls the window title, and defaults to 'Pick a File': DirVars.StrPromptFileTitle: string[60]; Changing the Buttons Both the text and the associated hot key of each of the three buttons may be changed by modifying the following variables: DirVars.OpenButStr: strbutton; DirVars.OpenHK: word; DirVars.CancelButStr: strbutton; DirVars.CancelHK: word; DirVars.HelpButStr: strbutton; DirVars.HelpHK: word; The defaults for these variables are as follows: OpenButStr := ' ~O~pen '; CancelButStr := ' ~C~ancel '; HelpButStr := ' ~H~elp '; OpenHK := 280; CancelHK := 302; HelpHK := 291; Run the demo DEMDIR3.PAS to see a custom Save As dialog that was developed by modifying the buttons and title. Changing Error Dialogs When the user selects a drive which is not available or ready (e.g. when the user selects a floppy drive when no disk is in the drive), Gold displays an error dialog. The error title and text can be customized by modifying the following variables: DirVars.NotReadyTitle: string [30]; DirVars.NotReadyMsgA: string [30]; DirVars.NotReadyMsgB: string [60]; The default text for these variables is as follows: NotReadyTitle := 'Drive not ready!'; NotReadyMsgA := 'Cannot read drive '; NotReadyMsgB := 'Please insert a disk or select Cancel'; When a user enters the name of a file which does not exist, and DirVars. ExistsOnly is set to true, an error is displayed. The error title and text can be customized by modifying the following variables: DirVars.NoExistTitle: string [30]; DirVars.NoExistText: string [60]; The default text for these variables is as follows: NoExistTitle := ' INVALID '; NoExistText := '||^Not a valid path or file name'; Customizing PromptFile Colors If (for some inexplicable reason) you have the urge to change the default colors used in the file dialog, read on. If you are not familiar with Gold's Tint system, read the section Customizing Display Colors in Chapter 3 before proceeding. When changing the colors, it helps to realize that the dialog is actually an IO form (yes we use our own tools) and many of the colors are modified by altering the default IO colors. Listed below is an extract from the demo file DEMDIR4.PAS which customizes every component of the dialog: procedure CustomizeColors; {} begin {first the window border} GoldSetColor(IOWinTitle,WhiteonMagenta); GoldSetColor(IOWinIcons,GreenonMagenta); GoldSetColor(IOWinBorder1,YellowonMagenta); GoldSetColor(IOWinBody,YellowonMagenta); {now the buttons} GoldSetColor(IOButtonNormHot,WhiteOnBlue); GoldSetColor(IOButtonNorm,YellowOnBlue); GoldSetColor(IOButtonHiHot,WhiteonRed); GoldSetColor(IOButtonHi,YellowOnRed); {now the list fields} GoldSetColor(ListHi1,WhiteOnRed); GoldSetColor(ListNorm1,LightcyanOnBlue); GoldSetColor(ListScrollBarHi,LightcyanOnBlue); {and finally the messages} GoldSetColor(IOLabelNorm,CyanOnMagenta); GoldSetColor(IOLabelHi,LightcyanOnMagenta); end; { CustomizeColors } Using PromptDir to Choose a Directory If you want to get the user to select a directory, use PromptDir as follows: PromptDir(FullFilename:PathStr;Cmt:StrScreen): StrScreen; Displays a directory selection dialog allowing the user to navigate around the drives and directories and select a path. The first parameter is a string that specifies the default path that will be selected when the dialog is first displayed. The second parameter is an optional comment which will be inserted at the top of the dialog. If the user escapes, a null string is returned, otherwise the selected directory (fully-qualified) is returned. Like PromptFile, PromptDir supports a custom help button when the procedure AssignDirHelpHook is used to assign a custom help procedure. Run the demos DEMDIR3.PAS and DEMDIR4.PAS to see PromptDir in action. (See Figure 6.2) Customizing the PromptDir Dialog The window title, button text and button hotkeys can all be customized to change the flavor of the dialog. International developers can easily change all the dialog text and messages to a different language. The DirVars record variable includes the following variables which influence the displayed text: Changing the Window Title The following variable controls the window title and defaults to 'Change directory' : DirVars.StrPromptDirTitle : string[60]; Figure 6.2 The PromptDir dialog Changing the Buttons Both the text and the associated hot key of each of the three buttons may be changed by modifying the following variables: DirVars.OKButStr: strButton; DirVars.OKHK: word; DirVars.CancelButStr: strbutton; DirVars.CancelHK: word; DirVars.HelpButStr: strbutton; DirVars.HelpHK: word; The defaults for these variables are as follows: OKButStr := ' ~O~K '; CancelButStr := ' ~C~ancel '; HelpButStr := ' ~H~elp '; OKHK := 280; CancelHK := 302; HelpHK := 291; The error text for error dialogs can be changed in the manner described in the section Changing Error Dialogs on page 6-3. Customizing PromptDir Colors The technique for customizing the PromptDir colors is similar to PromptFile (discussed earlier). Listed below is an extract of the demo program DEMDIR7.PAS which assigns custom colors to the dialog. procedure CustomizeColors; {} begin {first the window border} GoldSetColor(IOWinTitle,WhiteonMagenta); GoldSetColor(IOWinIcons,GreenonMagenta); GoldSetColor(IOWinBorder1,YellowonMagenta); GoldSetColor(IOWinBody,YellowonMagenta); {now the buttons} GoldSetColor(IOButtonNormHot,WhiteOnBlue); GoldSetColor(IOButtonNorm,YellowOnBlue); GoldSetColor(IOButtonHiHot,WhiteonRed); GoldSetColor(IOButtonHi,YellowOnRed); {now the list fields} GoldSetColor(ListHi1,WhiteOnRed); GoldSetColor(ListNorm1,LightcyanOnBlue); GoldSetColor(ListScrollBarHi,LightcyanOnBlue); {and finally the messages} GoldSetColor(IOLabelNorm,CyanOnMagenta); GoldSetColor(IOLabelHi,LightcyanOnMagenta); end; { CustomizeColors } Using FileList to a Choose File FileList takes advantage of Gold's list management tools and displays a list of files in a multi-column list (see Figure 6.3). Run the demo file DEMDIR8.PAS to see FileList in action. To display a file list in a stretchable window call FileList which is defined as follows: FileList(FullFilename:PathStr; Tit:StrScreen): StrScreen; Displays a list of files in a list window. The first string parameter identifies the filemask. If the string includes a path, the path will be the start-up directory when the window is first displayed. The second parameter is an optional title. The function returns the fully-qualified filename of the selected file, or a null string if the user escaped. Figure 6.3 The FileList window FileList can display multiple file masks in a single list. All you have to do is specify multiple filemasks in the Fullfilename parameter. Try passing the string '*.pas *.asm *.inc'. You can still specify a full-qualified path on the first mask, e.g. 'c:\stuff\*.pas *.asm *.inc'. This technique will also work with the PromptFile command. Sorting the File List DirVars includes the boolean variable SortByName. If this variable is set to TRUE (the default being FALSE), Gold will sort the files in name order. Changing Informational Text Information about the highlighted file is displayed in a two line panel at the bottom of the window (see figure 7-2). The DirVars record variable includes the following variables which influence the text displayed in the panel: DirVars.ParentStr: string[30]; The string displayed when the highlight bar is on the '..' file. The default string is 'Parent directory'. DirVars.SubDirStr: string[30]; The string which is a prefix to a sub-directory name when a sub-directory is highlighted. The default string is 'Sub directory'. DirVars.RootStr: string[30]; The string displayed when the highlight bar is on the '\ (root)' file. The default string is 'Root directory'. DirVars.NoFilesStr: string[30]; The string displayed when no matching files are encountered in the active directory. DirVars.RootNameStr: string[12]; The "filename" of the list entry which, when selected, jumps the user to the root of the active drive. The default name is '\ (root)'. DirVars.DriveStr: string[20]; The string which is a prefix to a drive letter when a drive is highlighted. The default string is 'Drive'. DirVars.SortingStr: string[30]; The message string which is displayed at the top-left of the list window when Gold is sorting the filename list. The default string is 'Sorting files...'. Run the demos DEMDIR8.PAS through DEMDIR11.PAS for examples of customizing the FileList display. Customizing the FileList Display Colors The display colors used by FileList are controlled by setting the defaults in GOLDTINT. The demo file DEMDIR12.PAS illustrate how to customize all the display colors used by FileList. Listed below is an extract from this demo file: procedure CustomizeColors; {} begin {first the window border} GoldSetColor(ListTitle,WhiteonMagenta); GoldSetColor(ListIcons,LightgrayOnMagenta); GoldSetColor(ListBorder1,YellowonMagenta); GoldSetColor(ListBorder2,BlackonMagenta); GoldSetColor(ListNorm1,BlackonMagenta); {now the list fields} GoldSetColor(ListNorm1,YellowOnMagenta); {files} GoldSetColor(ListHi1,WhiteOnCyan); GoldSetColor(ListNorm2,WhiteOnMagenta); {directories and drives} GoldSetColor(ListHi2,BlackOnCyan); GoldSetColor(ListScrollBarHi,LightgrayOnMagenta); {now the file info} GoldSetColor(DirListInfo,LightgrayonMagenta); end; { CustomizeColors } Error Handling All the directory and file displaying functions discussed in this chapter have the potential to fail. For example, there may be insufficient memory to display all the files. After calling one of the functions, always call the function LastDirError to see if the operation was successful. One final note. If you want to display a list of files and allow the user to select multiple files, create a custom list using the RunList command. This technique is explained in Chapter 14 and can be viewed in the demo file DEMLS4.PAS.